home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1995 October / EnigmA AMIGA RUN 01 (1995)(G.R. Edizioni)(IT)[!][issue 1995-10][Aminet 7].iso / Aminet / comm / fido / SHELTER275.lha / DOCS / xpremsi.doc < prev   
Text File  |  1994-09-19  |  14KB  |  375 lines

  1.  
  2.         A Library for EMSI handshake for WPL Mailers by Gordon Normand
  3.  
  4.     XPRemsi.library  is  an  XPR  v3 library for Shelter Mailers that talks
  5. directly  to wpl.library.  It does not work with any other XPR host.  It is
  6. not  a  direct replacement for the restricted distribution wplemsi.library,
  7. but can be used in those environments with some wpl code modification.
  8.  
  9.     The library simply sends and receives EMSI packets and calculates CRCs.
  10. All  values  to  be  sent must be set by the host mailer.  Any action to be
  11. taken based upon received values is up to the host mailer.
  12.  
  13.     Much  of  this  documentation is based upon public messages from Robert
  14. Williamson, the author of the Shelter Mailers, in the FIDONET echos NET_DEV
  15. and  WELMAT  and  in  the INTERNET WPL mailing lists.  Much information was
  16. also  gleaned  from  the  Porticus  Mailer  WPL  code.   This powerful EMSI
  17. implementation is the most extensive available on the Amiga.
  18.  
  19.  
  20.     References:
  21.         WPL.Language,  wpl application developers language reference,
  22.         WPL.Programmer, wpl  developers interface reference,
  23.          by Russell McOrmond
  24.         FSC-0056.001, The EMSI/IEMSI Protocol Definitions 
  25.          by Joaquim H. Homrighausen
  26.         EMSI-II,  EMSI/IEMSI Protocol Clarifications and Enhancements
  27.          by Robert Williamson
  28.  
  29.     Calling:
  30.         Inbound Calls:
  31.             XprSetup xpremsi.library ""
  32.             XprReceive ""
  33.             XprClose
  34.             set RC $(EMSI)
  35.  
  36.         Outbound Calls:
  37.  
  38.             XprSetup xpremsi.library ""
  39.             XprSend ""
  40.             XprClose
  41.             set RC $(EMSI)
  42.  
  43.         $(EMSI) is TRUE if handshake was OK, else FALSE.
  44.  
  45.         The following variables should be set before calling the xpr.
  46.  
  47.         ${WPLNAME}
  48.             An environmental variable which contains a string with the name
  49.         and version of the host mailer.
  50.  
  51.         $(baud)
  52.            The current link rate (modem<->modem, automatically set).
  53.  
  54.         $(remote.password)
  55.             The password for the remote site as defined in site cache or
  56.         nodelist.
  57.  
  58.         $(host.akas)
  59.             A list of addresses in EMSI format:
  60.                     zone:net/node[.point][@domain]
  61.         The  first  AKA  is  considered  to be the PRIMARY address, and
  62.         should be one's address in the domain of the site we are calling.
  63.  
  64.         $(host.phone)
  65.             full phone number as in nodelist
  66.         $(host.baud)
  67.             max bps as in nodelist
  68.         $(host.flags)
  69.             nodelist flags as in nodelist
  70.         $(host.sysop)
  71.             sysop names as in nodelist
  72.         $(host.city)
  73.             location as in nodelist
  74.         $(host.sitename)
  75.             system name as in nodelist
  76.         $(host.serial)
  77.             name and version info set by host application
  78.         $(host.freq)
  79.             If false, the NRQ flag will be sent for INBOUND calls.
  80.  
  81.         $(host.link)
  82.         $(host.compat)
  83.             see below
  84.  
  85.     Additional  EMSI  fields  can  be added, if the following convention is
  86. followed:
  87.  
  88.     Set host.flags "$(host.flags)]}{TRX#}{[$(RESULT2)]}{[UTC]}{[${TZ}"
  89.  
  90.     As  can  be seen, the additional fields are tacked on to the host.flags
  91. variable.   The  library adds the data field's [,],{ and } to the variables
  92. contents.   The  first pair of "]}" terminate the emsi IDENT structure, the
  93. final pair is added by the library itself.
  94.  
  95.  
  96.     If the handshake was successful, the following variables will be set.
  97.  
  98.         host.compat
  99.             set to selected protocol (see below)           
  100.             
  101.         remote.akas
  102.             a list AKAS in EMSI format (zone:net/node[.point][@domain])
  103.             the first AKA is considered to be the PRIMARY address.
  104.         remote.address
  105.             set to primary address in EMSI format
  106.  
  107.         remote.freq
  108.             this variable is set FALSE if remote site presents HRQ
  109.     
  110.         remote.password
  111.             the password the remote site presented
  112.  
  113.         remote.link
  114.         remote.compat
  115.             see below
  116.                         
  117.         remote.product
  118.             FTSC product code
  119.         remote.mailer
  120.             Mailer name
  121.         remote.version
  122.             Mailer version
  123.         remote.serial
  124.             serial number or other product specific identification
  125.         remote.extra
  126.  
  127.         remote.sitename
  128.         remote.city
  129.         remote.sysop 
  130.         remote.phone
  131.         remote.baud
  132.         remote.flags
  133.             All  the  above  are the remote sites system information.  This
  134.         may  or  may not be the same as what apprears in the Nodelist entry
  135.         for that site.
  136.  
  137.         remote.time
  138.             transaction timestamp
  139.  
  140.  
  141.  
  142.     The   remainder   is   extracted   from   Robert  Williamson's  EMSI-II
  143. specification  and  is  used by permission.  The extract describes the EMSI
  144. Link  and  Compatibity  flags which are direcetly related to the host.  and
  145. remote.  link and compat variables.
  146.  
  147.     Link and Compatibility Flag Processing:
  148.  
  149.     Link Flags:
  150.     Link  flags  consist  of a string of codes that specify DESIRED CONNECT
  151. CONDITIONS.  They apply to the CURRENT SESSION ONLY.  There are three TYPES
  152. of link flags:  communications parameters, pickup options and hold options.
  153.  
  154.     Link Communications Parameters:
  155.     Presented  by  both  the calling system and answering system, this flag
  156. defines the communications link data bits, stop bits and parity parameters.
  157. The  purpose  of  this flag is unclear however, my assumption is that it is
  158. expected  that one end or the other change his communications parameters to
  159. match.   The specification does not say which end must compromise, nor what
  160. to  do  if  a)  no  compromise  is  possible,  b) software does not support
  161. changing  these  parameters  while  connected.   Obviously, if only one end
  162. changes link parameters, the session will fail.
  163.  
  164.  
  165.     Pickup and Hold Flags:
  166.     Under  a  strict  interpretation of the EMSI specification, Link Pickup
  167. flags  are  only  presented  when  calling  (an  Outbound  Session) and are
  168. examined  and  processed  only when answering (an Inbound Session) and Link
  169. Hold  flags  are only presented when answering (an Inbound Session) and are
  170. examined and processed only when calling (an Outbound Session).
  171.  
  172.     Some  mailers  optionally  present  BOTH  Pickup  and Hold flags during
  173. EITHER  type  of session.  However, there is no requirement that the system
  174. received  such a presentation take an action on flags not specified for the
  175. type of session.  There are also no guidelines how to handle conflicts that
  176. may arise in iterpretation.
  177.  
  178.  
  179.     Link Pickup options:
  180.         The  calling  system  can  present one of three Link Pickup options
  181. related  to  pickup of mail.  These are presented during OUTGOING calls and
  182. examined during INCOMING calls.
  183.  
  184.          /  PUA        Pickup mail for all presented addresses.
  185.  one of |   PUP        Pickup mail for primary address only.
  186.          \  NPU        No mail pickup desired.
  187.  
  188.     If none of these flags are presented, PUA is to be assumed.
  189.     If  only  one  address  is  presented,  neither  PUP  nor PUA should be
  190. presented, as this would be redundant.  NPU is valid however.
  191.  
  192.  
  193.     PUA:
  194.         This flag is presented if our tosser is zone and/or domain aware.
  195.  
  196.         This  flag  is  not  examined, since sending all mail for all KNOWN
  197. akas  is  the  default  action under EMSI.  The action to take if NO Pickup
  198. flag is presented is undefined in the EMSI spec.  We assume PUA.
  199.  
  200.     Note:   KNOWN  akas  are  those addresses of a site for which one packs
  201. mail.   Since no traffic exists for a sites other unKNOWN AKAS, they are of
  202. no interest and are ignored.
  203.  
  204.     PUP:
  205.         This  flag  is  presented  if  our tosser is not zone and/or domain
  206. aware.  On outgoing calls the Primary address is always that address in the
  207. domain  of the site we are calling.  We will still present PUP, but this is
  208. redundant.
  209.  
  210.         When examined, mail is sent for Primary (first) address presented.
  211.  
  212.     NPU:
  213.         This flag is presented when using the NOPICKUP session option.  The
  214. presentation  of  NPU  is  a  courtesy  measure ONLY, since we hangup after
  215. sending our mail.
  216.  
  217.         When  examined,  NO  files  are sent, mail or OTHERWISE, UNLESS the
  218. remote  also  presented  PUP.   This  would be an error on his part, but we
  219. ignore that fact :) and just give him what he wanted.
  220.  
  221.  
  222.     Link Hold options:
  223.         When  answering,  the  site  can  present Link Hold flags which are
  224. requests  to  the  calling  site to not send certain types of files.  These
  225. flags  should  be  presented  only  on  incoming calls and examined only on
  226. outgoing calls.
  227.  
  228.              HRQ        Hold file requests (not processed at this time).
  229.  and/or
  230.          /   HAT        Hold ALL traffic.
  231.  one of |
  232.          \   HXT        Hold compressed mail traffic.
  233.  
  234.  
  235.     HRQ:
  236.         This flag is presented during UMH if STRICTZMH is TRUE.
  237.         This  flag  is  also presented if file request processing is disabled
  238. TEMPORARILY for any reason.
  239.  
  240.         When examined, file requests are not sent to remote site.
  241.  
  242.     HAT:
  243.         Presented if inbound free space has fallen below a preset limit.
  244.  
  245.         When examined, no files are sent, but files can be received.
  246.  
  247.     HXT:
  248.         This flag is presented during UMH if STRICTZMH is TRUE.
  249.  
  250.         When examined, system specific processing determines what files are
  251. sent.
  252.  
  253.  
  254.     Note:   STRICTZMH  would  mean that only netmail packets may be sent or
  255. received.   There  should  be  no  file  request  accepted or processed, no
  256. arcmail accepted or sent and no fileechos (TIC's) accepted or sent.
  257.  
  258.  
  259.     Compatibility Flags:
  260.  
  261.         Compatibility  flags  consist of a string of codes that specify the
  262. CAPABILITIES  (protocols  and archivers) and ENABLED FEATURES (file request
  263. handler, filename conversion) of the mailer.
  264.  
  265.     Standard Protocol Flags:
  266.  
  267.         NCP     No common protocol ( a failure )
  268.  
  269.         DZA     DirectZAP (Zmodem variant).
  270.         ZAP     ZedZap (Zmodem variant).
  271.         ZMO     Zmodem w/1,024 byte data packets (Wazoo ZedZip).
  272.         JAN     Janus
  273.         KER     Kermit
  274.         SLK     SeaLink
  275.  
  276.     Extended Protocol Flags:
  277.  
  278.         TEL     Telink  (FTS1)
  279.         XMO     Xmodem  (DietIFNA)
  280.         YMO     Ymodem
  281.         UUG     uucp-g
  282.         HYD     Hydra
  283.  
  284.  
  285.     NCP:
  286.         This  is presented if no compatible protocols (failure).  It logged
  287. if  the remote presents it.  Since in most networks, a common protocol DOES
  288. exist, we fall back to that protocol, DietIFNA.
  289.  
  290.     Note:   Versions  of  Binkley,  Porticus,  Gazebo, Umbrella and JamMail
  291. feature DietIFNA fallback.
  292.  
  293.     Other Compatibility flags:
  294.  
  295.         NRQ     No file requests accepted by this system.
  296.  
  297.     NRQ:
  298.         This  flag should be presented if there is NO FILE REQUEST HANDLER.
  299. ie the system NEVER accepts file requests.
  300.  
  301.         When examined, No requests will be sent.
  302.  
  303. **NOTE:
  304.         It  seems  some mailers present NRQ as the caller's version of HRQ.
  305. I consider this action to be incorrect since:
  306.  
  307.     - Well written mailers NEVER process requests received during outbound
  308.       sessions
  309.     - NRQ flag indicates NO REQUEST SERVER AVAILABLE
  310.     - HRQ flag indicates NO REQUESTS AT THIS TIME.
  311.     - Under  WAZOO,  the  lack of a NODELIST X?  flag can be seen as  
  312.       the equivalent to EMSI presentation of NRQ
  313.  
  314.         NRQ  should  be  presented  ONLY  IF  the mailer does not have a file
  315. request  server.   It  should  NOT be used to indicate that the function is
  316. temporarly disabled.
  317.  
  318.         If  the  author  of the EMSI specification had intended that NRQ be
  319. the  caller's  version  of  HRQ,  why  then  are  there  separate  LINK and
  320. COMPATIBILTY flags, if they are not consistanty applied?  Why was there any
  321. distinction made between calling and answering system LINK flags?  It would
  322. be more consistant if ALL LINK flags be presentable by either system.
  323.         In  fact,  for  consistancy,  the  chosen  protocol  should also be
  324. presented as a LINK flag.
  325.  
  326.         ARC     ARCmail 0.60-capable, as defined by the FTSC.
  327.                 NO ACTION required, information is of little value.
  328.  
  329.         XMA     Site supports other forms of compressed mail.
  330.                 NO ACTION required, information is of little value.
  331.     
  332.         FNC     Filename conversion. This indicates that any transmitted
  333.                 filename must follow the CP/M & MS-DOS 8.3 restriction.
  334.                 An eight  character file name followed by a three character
  335.                 extension; eg. FILENAME.EXT
  336.  
  337. **NOTE:
  338.         Since FNC is a COMPATIBILITY flag, it SHOULD be interpreted to mean
  339. that  the  system  presenting FNC is advertising the CAPABILITY to send 8.3
  340. file  names.  If the intention of the author of the EMSI spec was that this
  341. was  a  request  for the other end to modify filenames, this should have be
  342. stated.  The word 'received' should have been used instead of 'transmitted'
  343. and the FNC flag should have been defined as a LINK flag for consistancy in
  344. the specification.
  345.  
  346.     Accepting  the  fact  the some systems actually intend the flag to be a
  347. request  for  the  remote to convert filenames before sending, I have added
  348. this  capability  to  RFH,  my file request handler.  FNC conversion is not
  349. required for mail or packets since the transmitted filenames always conform
  350. to the FTS-LIST specifications.
  351.  
  352.     While  doing  this,  it  occured  to me that the above spec is somewhat
  353. unclear.   Specifically, it does not mention what characters may be illegal
  354. in  cp/m  and  msdos  filenames.   In  fact, since this flag may be used by
  355. mailers   on   other   platforms,   simply  stripping  such  characters  is
  356. insufficent.   Other platforms use characters in filenames that are illegal
  357. under msdos and msdos uses characters that are illegal on other platforms.
  358.  
  359.     Therefore, it would seem advisable that any FNC function should:
  360.  
  361.     - Strip ALL punctuation including embedded periods, 
  362.       except for the last period (.) which now separts the name and
  363.       extension fields.
  364.       I strip: '20'x-'2f'x, '3a'x-'40'x, '5b'x-'60'x, '7b'x-'7f'x
  365.  
  366.     - Convert to UPPERCASE
  367.  
  368.     - pad each field with trailing '0's to insure they are at least 8
  369.       and 3 in length
  370.     
  371.     - re-build the filename from the FIRST and LAST 4 characters of the
  372.       name field and the FIRST three characters of the extension field.
  373.  
  374.  
  375.